Inside Macintosh: QuickTime Components /: Chapter 12 - Preview Components

Creating Preview Components

This section describes how to create your own preview component.

Preview components that create previews have a type of 'pmak' and a subtype that matches the type of the file for which they create previews.

Preview components that display previews have a type of 'pnot' and a subtype that matches the type of the resource that they display.

You can use the following constants to refer to the request codes for each of the functions that your preview component must support.

enum {
   kPreviewShowDataSelector            = 1, /* PreviewShowData */
   kPreviewMakePreviewSelector         = 2, /* PreviewMakePreview */
   kPreviewMakePreviewReferenceSelector = 3,/* PreviewMakePreviewReference */
   kPreviewEventSelector               = 4  /* PreviewEvent */
};

This section presents a sample program that displays a preview component for the display of PICS animation files. First it implements the required Component Manager functions. Then it converts the PICT image data into a format for display as a preview.

Implementing Required Component Functions

Listing 12-1 supplies the component dispatchers for the preview component together with the can do, version, open, and close functions.

Listing 12-1 Implementing the required Component Manager functions

typedef struct {
   ComponentInstance self;
} PICSPreviewRecord, **PICSPreviewGlobals;
/* entry point for all Component Manager requests */
pascal ComponentResult PICSPreviewDispatch 
                     (ComponentParameters *params, Handle store)
{
   OSErr err = badComponentSelector;
   ComponentFunction componentProc = 0;
   switch (params->what) {
      case kComponentOpenSelect: 
         componentProc = PICSPreviewOpen; break;
      case kComponentCloseSelect: 
         componentProc = PICSPreviewClose; break;
      case kComponentCanDoSelect: 
         componentProc = PICSPreviewCanDo; break;
      case kComponentVersionSelect: 
         componentProc = PICSPreviewVersion; break;
      case kPreviewShowDataSelector: 
         componentProc = PICSPreviewShowData; break;
   }
   if (componentProc)
      err = CallComponentFunctionWithStorage (store, params,
                                              componentProc);
   return err;
}
pascal ComponentResult PICSPreviewCanDo 
                     (PICSPreviewGlobals store, short ftnNumber)
{
   switch (ftnNumber) {
      case kComponentOpenSelect:
      case kComponentCloseSelect:
      case kComponentCanDoSelect:
      case kComponentVersionSelect:
      case kPreviewShowDataSelector:
         return true;
      default:
         return false;
   }
}
pascal ComponentResult PICSPreviewVersion 
                              (PICSPreviewGlobals store)
{
   return 0x00010001;
}
pascal ComponentResult PICSPreviewOpen (PICSPreviewGlobals store,
                               ComponentInstance self)
{
   store = (PICSPreviewGlobals)NewHandle 
                              (sizeof (PICSPreviewRecord));
   if (!store) return MemError();
   SetComponentInstanceStorage (self, (Handle)store);
   (**store).self = self;
   return noErr;
}
pascal ComponentResult PICSPreviewClose 
                              (PICSPreviewGlobals store,
                              ComponentInstance self)
{
   if (store) DisposeHandle ((Handle)store);
   return noErr;
}

Displaying Image Data as a Preview

To display a file's image preview, your PreviewShowData function is called.
Listing 12-2 includes the PICSPreviewShowData function, which previews a PICS file. The function loads the first PICT image from the PICS file and uses the PICT file preview component to display it.

Listing 12-2 Converting data into a form that can be displayed as a preview

pascal ComponentResult PICSPreviewShowData 
                                 (PICSPreviewGlobals store,
                                  OSType dataType, Handle data,
                                  const Rect *inHere)
{
   OSErr err = noErr;
   short resRef = 0, saveRes = CurResFile();
   FSSpec theFile;
   Boolean whoCares;
   Handle thePict = nil;
   ComponentInstance ci;
   /* because your component has the pnotComponentNeedsNoCache
      flag set, it should only be called to display files */
   if (dataType != rAliasType)
      return paramErr;
   /* open up the file to preview */
   if (err = ResolveAlias (nil, (AliasHandle)data, &theFile,
                         &whoCares)) goto bail;
   resRef = FSpOpenResFile (&theFile, fsRdPerm);
   if (err = ResError()) goto bail;
   /* get the first 'PICT' */
   UseResFile (resRef);
   thePict = Get1IndResource ('PICT', 1);
   if (!thePict) goto bail;
   /* use the PICT preview component to display the preview */
   if (ci = OpenDefaultComponent (ShowFilePreviewComponentType,
                                  'PICT')) {
      PreviewShowData (ci, 'PICT', thePict, inHere);
      CloseComponent (ci);
   }
bail:
   if (resRef) CloseResFile (resRef);
   if (thePict) DisposeHandle (thePict);
   UseResFile (saveRes);
   return err;
}

Subtopics
Implementing Required Component Functions

Displaying Image Data as a Preview